Foreign Procedure Calls

The interface between T3 and the local operating system is the define-foreign special form:


(define-foreign T-name (foreign-name parameterstex2html_wrap_inline$^+$ ) return-type) $\Longrightarrow$ undefined syntax

define-foreign defines a foreign procedure, i.e. a T procedure which will call a procedure defined by the operating system or in another language.

T-name
is the name of the T procedure being defined.

foreign-name
is the name of the foreign procedure to which the T-name corresponds.

parameters
specifies the representation of the parameters to the foreign procedure or function.

return-type
indicates the representation of the value returned by the foreign procedure.

formula vobeyspaces :
!:} parameter → (parameter-type foreign-type [parameter-name])

parameter-type → { in | out | in/out | var | ignore }

foreign-type → { rep/integer | rep/integer-8-s | rep/integer-8-u | rep/integer-16-s | rep/integer-16-u | rep/value | rep/extend | rep/extend-pointer | rep/string | rep/string-pointer }

parameter-name → symbol used for identification

return-type → Aegis: { foreign-type | ignore | rep/address } Unix: { foreign-type | ignore }

For example, on the Apollo a procedure to do block reads from a stream would be defined as follows:

formula vobeyspaces :
!:} (define-foreign aegis-read (stream_$get_buf (in rep/integer-16-u stream-id) (in rep/string bufptr) (in rep/integer buflen) (ignore rep/integer retptr) (out rep/integer retlen) (ignore rep/extend seek-key) (out rep/integer status)) ignore)

The following code will use aegis-read to read in a string from standard input:

formula vobeyspaces :
!:} (let ((stream 0) (buf (make-string 128))) (receive (len status) (aegis-read stream buf 128 nil nil nil nil) (cond ((= 0 status) (set (string-length buf) len) len) (error ...))))

On a Unix machine a similar procedure would be defined as,

formula vobeyspaces :
!:} (define-foreign unix-read-extend (read (in rep/integer) (in rep/string) (in rep/integer)) rep/integer)

To read a string from standard input on Unix the T code would look something like:

formula vobeyspaces :
!:} (let ((buf (make-string 128))) (receive (len status) (unix-read 0 buf 128) (cond ((> 0 status ) (set (string-length buf) len) len) (error ...))))


Subsections